home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / lang / lisp / guile-ii.src / guile-ii / guile-src / guile-docs / user / scm.info-1 < prev    next >
Encoding:
GNU Info File  |  1995-06-08  |  47.0 KB  |  1,427 lines
  1. This is Info file scm.info, produced by Makeinfo-1.55 from the input
  2. file scm.texi.
  3.  
  4. 
  5. File: scm.info,  Node: Top,  Next: Copying,  Prev: (dir),  Up: (dir)
  6.  
  7.   This file documents the SCM Scheme implementation.
  8.  
  9.   Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Aubrey Jaffer
  10.  
  11.   Permission is granted to make and distribute verbatim copies of this
  12. manual provided the copyright notice and this permission notice are
  13. preserved on all copies.
  14.  
  15.   Permission is granted to copy and distribute modified versions of this
  16. manual under the conditions for verbatim copying, provided that the
  17. entire resulting derived work is distributed under the terms of a
  18. permission notice identical to this one.
  19.  
  20.   Permission is granted to copy and distribute translations of this
  21. manual into another language, under the above conditions for modified
  22. versions, except that this permission notice may be stated in a
  23. translation approved by the author.
  24.  
  25. * Menu:
  26.  
  27. * Copying::
  28. * Overview::                    Whats here and how to start using it.
  29. * Installing SCM::
  30. * Standard Facilities::
  31. * Packages::                    Optional Capabilities
  32. * Guile Facilities::            Brave new World
  33. * Internals::                   How it works
  34. * Procedure and Macro Index::
  35. * Variable Index::
  36. * Type Index::
  37.  
  38. 
  39. File: scm.info,  Node: Copying,  Next: Overview,  Prev: Top,  Up: Top
  40.  
  41. Copying
  42. *******
  43.  
  44.                          COPYRIGHT (c) 1989 BY
  45.  
  46.       PARADIGM ASSOCIATES INCORPORATED, CAMBRIDGE, MASSACHUSETTS.
  47.  
  48.                           ALL RIGHTS RESERVED
  49.  
  50. Permission to use, copy, modify, distribute and sell this software and
  51. its documentation for any purpose and without fee is hereby granted,
  52. provided that the above copyright notice appear in all copies and that
  53. both that copyright notice and this permission notice appear in
  54. supporting documentation, and that the name of Paradigm Associates Inc
  55. not be used in advertising or publicity pertaining to distribution of
  56. the software without specific, written prior permission.
  57.  
  58. PARADIGM DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
  59. INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO
  60. EVENT SHALL PARADIGM BE LIABLE FOR ANY SPECIAL, INDIRECT OR
  61. CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF
  62. USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
  63. OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
  64. PERFORMANCE OF THIS SOFTWARE.
  65.  
  66. gjc@paradigm.com
  67.                                                     Phone: 617-492-6079
  68.  
  69. Paradigm Associates Inc
  70. 29 Putnam Ave, Suite 6
  71. Cambridge, MA 02138
  72.  
  73.            Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995
  74.  
  75.                     Free Software Foundation, Inc.
  76.  
  77.                 675 Mass Ave, Cambridge, MA 02139, USA
  78.  
  79. Permission to use, copy, modify, distribute, and sell this software and
  80. its documentation for any purpose is hereby granted without fee,
  81. provided that the above copyright notice appear in all copies and that
  82. both that copyright notice and this permission notice appear in
  83. supporting documentation.
  84.  
  85.                               NO WARRANTY
  86.  
  87. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR
  88. THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
  89. OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
  90. PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
  91. EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  92. WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE
  93. ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH
  94. YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
  95. NECESSARY SERVICING, REPAIR OR CORRECTION.
  96.  
  97. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
  98. WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
  99. REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR
  100. DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
  101. DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
  102. (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED
  103. INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
  104. THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR
  105. OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
  106.  
  107. 
  108. File: scm.info,  Node: Overview,  Next: Installing SCM,  Prev: Copying,  Up: Top
  109.  
  110. Overview
  111. ********
  112.  
  113. Scm is a portable Scheme implementation written in C.  Scm provides a
  114. machine independent platform for [JACAL], a symbolic algebra system.
  115.  
  116. * Menu:
  117.  
  118. * SCM Features::
  119. * SCM Authors::
  120. * Bibliography::
  121. * Invoking SCM::
  122. * SCM Options::
  123. * SCM Variables::
  124. * SCM Examples::
  125. * SCM Session::
  126.  
  127. 
  128. File: scm.info,  Node: SCM Features,  Next: SCM Authors,  Prev: Overview,  Up: Overview
  129.  
  130. Features
  131. ========
  132.  
  133.    * Conforms to Revised^4 Report on the Algorithmic Language Scheme
  134.      [R4RS] and the [IEEE] P1178 specification.
  135.  
  136.    * Support for [SICP], [R2RS], [R3RS], and (proposed) [R5RS] scheme
  137.      code.
  138.  
  139.    * Runs under Amiga, Atari-ST, MacOS, MS-DOS, OS/2, NOS/VE, Unicos,
  140.      VMS, Unix and similar systems.  Supports ASCII and EBCDIC
  141.      character sets.
  142.  
  143.    * Is fully documented in TeXinfo form, allowing documentation to be
  144.      generated in info, TeX, html, nroff, and troff formats.
  145.  
  146.    * Supports inexact real and complex numbers, 30 bit immediate
  147.      integers and large precision integers.
  148.  
  149.    * Many Common Lisp functions: `logand', `logor', `logxor', `lognot',
  150.      `ash', `logcount', `integer-length', `bit-extract', `defmacro',
  151.      `macroexpand', `macroexpand1', `gentemp', `defvar', `force-output',
  152.      `software-type', `get-decoded-time', `get-internal-run-time',
  153.      `get-internal-real-time', `delete-file', `rename-file',
  154.      `copy-tree', `acons', and `eval'.
  155.  
  156.    * `Char-code-limit', `most-positive-fixnum', `most-negative-fixnum',
  157.      `and internal-time-units-per-second' constants.  `*Features*' and
  158.      `*load-pathname*' variables.
  159.  
  160.    * Arrays and bit-vectors.  String ports and software emulation ports.
  161.      I/O extensions providing ANSI C and POSIX.1 facilities.
  162.  
  163.    * Interfaces to standard libraries including REGEX string regular
  164.      expression matching and the CURSES screen management package.
  165.  
  166.    * Available add-on packages including an interactive debugger,
  167.      database, X-window graphics, BGI graphics, Motif, and Open-Windows
  168.      packages.
  169.  
  170.    * A compiler (HOBBIT, available separately) and dynamic linking of
  171.      compiled modules.
  172.  
  173.    * User definable responses to interrupts and errors,
  174.      Process-syncronization primitives.  Setable levels of monitoring
  175.      and timing information printed interactively (the `verbose'
  176.      function).  `Restart', `quit', and `exec'.
  177.  
  178. 
  179. File: scm.info,  Node: SCM Authors,  Next: Bibliography,  Prev: SCM Features,  Up: Overview
  180.  
  181. Authors
  182. =======
  183.  
  184. Aubrey Jaffer (jaffer@ai.mit.edu)
  185.      Most of SCM.
  186.  
  187. Radey Shouman
  188.      Arrays. `gsubr's, compiled closures, and records.
  189.  
  190. Jerry D. Hedden
  191.      Real and Complex functions.  Fast mixed type arithmetics.
  192.  
  193. Hugh Secker-Walker
  194.      Syntax checking and memoization of special forms by evaluator.
  195.      Storage allocation strategy and parameters.
  196.  
  197. George Carrette
  198.      "Siod", written by George Carrette, was the starting point for SCM.
  199.      The major innovations taken from Siod are the evaluator's use of
  200.      the C-stack and being able to garbage collect off the C-stack
  201.      (*note Garbage Collection::.).
  202.  
  203. There are many other contributors to SCM.  They are acknowledged in the
  204. file `ChangeLog', a log of changes that have been made to scm.
  205.  
  206. 
  207. File: scm.info,  Node: Bibliography,  Next: Invoking SCM,  Prev: SCM Authors,  Up: Overview
  208.  
  209. Bibliography
  210. ============
  211.  
  212. [IEEE]
  213.      `IEEE Standard 1178-1990.  IEEE Standard for the Scheme
  214.      Programming Language.'  IEEE, New York, 1991.
  215.  
  216. [Simply]
  217.      Brian Harvey and Matthew Wright.  `Simply Scheme: Introducing
  218.      Computer Science' MIT Press, 1994 ISBN 0-262-08226-8
  219.  
  220. [SICP]
  221.      Harold Abelson and Gerald Jay Sussman with Julie Sussman.
  222.      `Structure and Interpretation of Computer Programs.' MIT Press,
  223.      Cambridge, 1985.
  224.  
  225. [R4RS]
  226.      William Clinger and Jonathan Rees, Editors.  Revised(4) Report on
  227.      the Algorithmic Language Scheme.  In `ACM Lisp Pointers IV'
  228.      (July-September 1991).
  229.  
  230.      *Note Top: (r4rs)Top.
  231.  
  232. [SLIB]
  233.      Todd R. Eigenschink, Dave Love, and Aubrey Jaffer.  SLIB, The
  234.      Portable Scheme Library.  Edition 2.01, for SLIB version 2a2,
  235.      January 1995.
  236.  
  237.      *Note Top: (slib)Top.
  238.  
  239. [JACAL]
  240.      Aubrey Jaffer.  JACAL Symbolic Mathematics System.  Version 1a5,
  241.      April 1994.
  242.  
  243.      *Note Top: (jacal)Top.
  244.  
  245. `scm.texi'
  246. `scm.info'
  247.      Documentation of `scm' extensions (beyond Scheme standards).
  248.      Documentation on the internal representation and how to extend or
  249.      include `scm' in other programs.
  250.  
  251. 
  252. File: scm.info,  Node: Invoking SCM,  Next: SCM Options,  Prev: Bibliography,  Up: Overview
  253.  
  254. Invoking SCM
  255. ============
  256.  
  257. scm  [-a kbytes] [-ibvqmu] [-p number]
  258.      [-c expression] [-e expression] [-f filename] [-l filename]
  259.      [-r feature] [- | - | -s] [filename] [arguments ...]
  260.  
  261. Upon startup `scm' loads the file specified by by the environment
  262. variable SCM_INIT_PATH or by the parameter IMPLINIT in the makefile (or
  263. `scmfig.h') if SCM_INIT_PATH is not defined. The makefiles attempt to
  264. set IMPLINIT to `Init.scm' in the source directory.
  265.  
  266. Unless the option `-no-init-file' occurs in the command line,
  267. `Init.scm' checks to see if there is file `ScmInit.scm' in the path
  268. specified by the environment variable HOME (or in the current directory
  269. if HOME is undefined). If it finds such a file it is loaded.
  270.  
  271. `Init.scm' then looks for command input from one of three sources: From
  272. an option on the command line, from a file named on the command line,
  273. or from standard input.
  274.  
  275. This explanation applies to SCMLIT or other builds of SCM.  GUILE is
  276. invoked similarly to SCM.  Guile's startup script is `Ginit.scm' rather
  277. than `Init.scm'.
  278.  
  279. Scheme-code files can also invoke SCM and its variants.  *Note #!:
  280. Syntax Extensions.
  281.  
  282. 
  283. File: scm.info,  Node: SCM Options,  Next: SCM Variables,  Prev: Invoking SCM,  Up: Overview
  284.  
  285. Options
  286. =======
  287.  
  288. The options are processed in the order specified on the command line.
  289.  
  290.  - Command Option: -a KBYTES
  291.      specifies that `scm' should allocate an initial heapsize of
  292.      KBYTES. This option, if present, must be the first on the command
  293.      line.
  294.  
  295.  - Command Option: -no-init-file
  296.      Inhibits the loading of `ScmInit.scm' as described above.
  297.  
  298.  - Command Option: -e EXPRESSION
  299.  - Command Option: -c EXPRESSION
  300.      specifies that the scheme expression EXPRESSION is to be
  301.      evaluated. These options are inspired by `perl' and `sh'
  302.      respectively. On Amiga systems the entire option and argument need
  303.      to be enclosed in quotes. For instance `"-e(newline)"'.
  304.  
  305.  - Command Option: -r FEATURE
  306.      requires FEATURE. This will load a file from [SLIB] if that
  307.      FEATURE is not already supported. If FEATURE is 2, 3, 4, or 5
  308.      `scm' will require the features neccessary to support [R2RS],
  309.      [R3RS], [R4RS], or proposed [R5RS], respectively.
  310.  
  311.  - Command Option: -l FILENAME
  312.  - Command Option: -f FILENAME
  313.      loads FILENAME. `Scm' will load the first (unoptioned) file named
  314.      on the command line if no `-c', `-e', `-f', `-l',  or `-s' option
  315.      preceeds it.
  316.  
  317.  - Command Option: -p LEVEL
  318.      sets the prolixity (verboseness) to LEVEL. This is the same as the
  319.      `scm' command (verobse LEVEL).
  320.  
  321.  - Command Option: -v
  322.      (verbose mode) specifies that `scm' will print prompts, evaluation
  323.      times, notice of loading files, and garbage collection statistics.
  324.      This is the same as `-p3'.
  325.  
  326.  - Command Option: -q
  327.      (quiet mode) specifies that `scm' will print no extra information.
  328.      This is the same as `-p0'.
  329.  
  330.  - Command Option: -m
  331.      specifies that subsequent loads, evaluations, and user
  332.      interactions will be with [R4RS] macro capability. To use a
  333.      specific [R4RS] macro implementation from [SLIB] (instead of
  334.      [SLIB]'s default) put `-r' MACROPACKAGE before `-m' on the command
  335.      line.
  336.  
  337.  - Command Option: -u
  338.      specifies that subsequent loads, evaluations, and user
  339.      interactions will be without [R4RS] macro capability. [R4RS] macro
  340.      capability can be restored by a subsequent `-m' on the command
  341.      line or from Scheme code.
  342.  
  343.  - Command Option: -i
  344.      specifies that `scm' should run interactively. That means that
  345.      `scm' will not terminate until the `(quit)' or `(exit)' command is
  346.      given, even if there are errors. It also sets the prolixity level
  347.      to 2 if it is less than 2. This will print prompts, evaluation
  348.      times, and notice of loading files. The prolixity level can be set
  349.      by subsequent options. If `scm' is started from a tty, it will
  350.      assume that it should be interactive unless given a subsequent `-b'
  351.      option.
  352.  
  353.  - Command Option: -b
  354.      specifies that `scm' should run non-interactively. That means that
  355.      `scm' will terminate after processing the command line or if there
  356.      are errors.
  357.  
  358.  - Command Option: -s
  359.      specifies, by analogy with `sh', that further options are to be
  360.      treated as program aguments.
  361.  
  362.  - Command Option: -
  363.  - Command Option: -
  364.      specifies that there are no more options on the command line.
  365.  
  366. 
  367. File: scm.info,  Node: SCM Variables,  Next: SCM Examples,  Prev: SCM Options,  Up: Overview
  368.  
  369. Environment Variables
  370. =====================
  371.  
  372.  - Environment Variable: SCM_INIT_PATH
  373.      is the pathname where `scm' will look for its initialization code.
  374.      The default is the file `Init.scm' in the source directory.
  375.  
  376.  - Environment Variable: SCHEME_LIBRARY_PATH
  377.      is the [SLIB] Scheme library directory.
  378.  
  379.  - Environment Variable: HOME
  380.      is the directory where `Init.scm' will look for the user
  381.      initialization file `ScmInit.scm'.
  382.  
  383. Scheme Variables
  384. ================
  385.  
  386.  - Variable: *argv*
  387.      contains the list of arguments to the program. `*argv*' can change
  388.      during argument processing. This list is suitable for use as an
  389.      argument to [SLIB] `getopt'.
  390.  
  391.  - Variable: *R4RS-macro*
  392.      controls whether loading and interaction support [R4RS] macros.
  393.      Define this in `ScmInit.scm' or files specified on the command
  394.      line. This can be overridden by subsequent `-m' and `-u' options.
  395.  
  396.  - Variable: *interactive*
  397.      controls interactivity as explained for the `-i' and `-b' options.
  398.      Define this in `ScmInit.scm' or files specified on the command
  399.      line. This can be overridden by subsequent `-i' and `-b' options.
  400.  
  401. 
  402. File: scm.info,  Node: SCM Examples,  Next: SCM Session,  Prev: SCM Variables,  Up: Overview
  403.  
  404. Examples
  405. ========
  406.  
  407. `% scm foo.scm'
  408.      Loads and executes the contents of `foo.scm' and then enters
  409.      interactive session.
  410.  
  411. `% scm -f foo.scm arg1 arg2 arg3'
  412.      Parameters `arg1', `arg2', and `arg3' are stored in the global
  413.      list `*argv*'; Loads and executes the contents of `foo.scm' and
  414.      exits.
  415.  
  416. `% scm -s foo.scm arg1 arg2'
  417.      Sets *argv* to `("foo.scm" "arg1" "arg2")' and enters interactive
  418.      session.
  419.  
  420. `% scm -e `(write (list-ref *argv* *optind*))' bar'
  421.      Prints `"bar"'.
  422.  
  423. `% scm -rpretty-print -r format -i'
  424.      Loads `pretty-print' and `format' and enters interactive session.
  425.  
  426. `% scm -r5'
  427.      Loads `dynamic-wind', `values', and [R4RS] macros and enters
  428.      interactive (with macros) session.
  429.  
  430. `% scm -r5 -r4'
  431.      Like above but `rev4-optional-procedures' are also loaded.
  432.  
  433. 
  434. File: scm.info,  Node: SCM Session,  Prev: SCM Examples,  Up: Overview
  435.  
  436. SCM Session
  437. ===========
  438.  
  439.    * Options, file loading and features can be specified from the
  440.      command line.  *Note System interface: (scm)System interface.
  441.      *Note Require: (slib)Require.
  442.  
  443.    * Typing the end-of-file character at the top level session (while
  444.      SCM is not waiting for parenthesis closure) causes SCM to exit.
  445.  
  446.    * Typing the interrupt character aborts evaluation of the current
  447.      form and resumes the top level read-eval-print loop.
  448.  
  449. 
  450. File: scm.info,  Node: Installing SCM,  Next: Standard Facilities,  Prev: Overview,  Up: Top
  451.  
  452. Installing SCM
  453. **************
  454.  
  455. * Menu:
  456.  
  457. * SLIB::
  458. * Problems Compiling::
  459. * Problems Linking::
  460. * Problems Running::
  461. * Testing::
  462. * Reporting Problems::
  463.  
  464. 
  465. File: scm.info,  Node: SLIB,  Next: Problems Compiling,  Prev: Installing SCM,  Up: Installing SCM
  466.  
  467. SLIB
  468. ====
  469.  
  470.   [SLIB] is a portable Scheme library meant to provide compatibility and
  471. utility functions for all standard Scheme implementations.
  472.  
  473.   Although SLIB is not *neccessary* to run SCM, I strongly suggest you
  474. obtain and install it.  Bug reports about running SCM without SLIB have
  475. very low priority.  SLIB is available from the same sites as SCM:
  476.  
  477.    * altdorf.ai.mit.edu:archive/scm/slib2a2.tar.gz
  478.  
  479.    * prep.ai.mit.edu:pub/gnu/jacal/slib2a2.tar.gz
  480.  
  481.    * ftp.maths.tcd.ie:pub/bosullvn/jacal/slib2a2.tar.gz
  482.  
  483.    * ftp.cs.indiana.edu:/pub/scheme-repository/imp/slib2a2.tar.gz
  484.  
  485. 
  486. File: scm.info,  Node: Problems Compiling,  Next: Problems Linking,  Prev: SLIB,  Up: Installing SCM
  487.  
  488. Problems Compiling
  489. ==================
  490.  
  491. FILE: PROBLEM
  492.      HOW TO FIX
  493.  
  494. *.c: include file not found
  495.      Correct the status of STDC_HEADERS in `scmfig.h'
  496.  
  497.      fix #include statement or add #define for system type to
  498.      `scmfig.h'.
  499.  
  500. *.c: Function should return a value in ...
  501. *.c: Parameter '...' is never used in ...
  502. *.c: Condition is always false in ...
  503. *.c: Unreachable code in function ...
  504.      Ignore.
  505.  
  506. scm.c: assignment between incompatible types
  507.      change SIGRETTYPE in `scm.c'.
  508.  
  509. time.c: CLK_TCK redefined
  510.      incompatablility between <stdlib.h> and <sys/types.h>.  remove
  511.      STDC_HEADERS in `scmfig.h'.
  512.  
  513.      edit <sys/types.h> to remove incompatability.
  514.  
  515. subr.c: Possibly incorrect assignment in function lgcd
  516.      Ignore.
  517.  
  518. sys.c: statement not reached
  519. sys.c: constant in conditional expression
  520.      ignore
  521.  
  522. sys.c: `???' undeclared, outside of functions
  523.      #undef STDC_HEADERS in `scmfig.h'.
  524.  
  525. scl.c: syntax error
  526.      #define SYSTNAME to your system type in `scl.c' (softtype)
  527.  
  528. 
  529. File: scm.info,  Node: Problems Linking,  Next: Problems Running,  Prev: Problems Compiling,  Up: Installing SCM
  530.  
  531. Problems Linking
  532. ================
  533.  
  534. PROBLEM
  535.      HOW TO FIX
  536.  
  537. _sin etc. missing.
  538.      uncomment LIBS in makefile
  539.  
  540. 
  541. File: scm.info,  Node: Problems Running,  Next: Testing,  Prev: Problems Linking,  Up: Installing SCM
  542.  
  543. Problems Running
  544. ================
  545.  
  546. PROBLEM
  547.      HOW TO FIX
  548.  
  549. Opening message and then machine crashes.
  550.      Change memory model option to C compiler (or makefile).
  551.  
  552.      Make sure `sizet' definition is correct in `scmfig.h'.
  553.  
  554.      Reduce size of HEAP_SEG_SIZE in `setjump.h'.
  555.  
  556. Input hangs
  557.      #define NOSETBUF
  558.  
  559. ERROR: heap: need larger initial
  560.      Need to increase the initial heap allocation using -a<kbytes> or
  561.      INIT_HEAP_SIZE.
  562.  
  563. ERROR: Could not allocate ...
  564.      Check `sizet' definition.
  565.  
  566.      Use 32 bit compiler mode.
  567.  
  568.      Don't try to run as subproccess
  569.  
  570. remove ... in scmfig.h and recompile scm
  571. add ... in scmfig.h and recompile scm
  572.      Do it and recompile files.
  573.  
  574. ERROR: `Init.scm' not found
  575.      Assign correct IMPLINIT in makefile or `scmfig.h' or define
  576.      environment variable `SCM_INIT_PATH' to be the full pathname of
  577.      `Init.scm' (*note Installing SCM::.).
  578.  
  579. WARNING: require.scm not found
  580.      define environment variable `SCHEME_LIBRARY_PATH' to be the full
  581.      pathname of the scheme library [SLIB] or change `library-vicinity'
  582.      in `Init.scm' to point to library or remove. *Note Installation:
  583.      (slib)Installation.
  584.  
  585.      Make sure the value of `(library-vicinity)' has a trailing file
  586.      separator (like / or \).
  587.  
  588. 
  589. File: scm.info,  Node: Testing,  Next: Reporting Problems,  Prev: Problems Running,  Up: Installing SCM
  590.  
  591. Testing
  592. =======
  593.  
  594. Loading `test.scm' in the distribution will run an [R4RS] conformance
  595. test on `scm'.
  596.  
  597.      > (load "test.scm")
  598.      -|
  599.      ;loading "test.scm"
  600.      SECTION(2 1)
  601.      SECTION(3 4)
  602.       #<primitive-procedure boolean?>
  603.          #<primitive-procedure char?>
  604.             #<primitive-procedure null?>
  605.                #<primitive-procedure number?>
  606.      ...
  607.  
  608. Loading `pi.scm' in the distribution will enable you to compute digits
  609. of pi.
  610.  
  611.      > (load "pi")
  612.      ;loading "pi"
  613.      ;done loading "pi.scm"
  614.      ;Evaluation took 20 mSec (0 in gc) 767 cells work, 233 bytes other
  615.      #<unspecified>
  616.      > (pi 100 5)
  617.      00003 14159 26535 89793 23846 26433 83279 50288 41971 69399
  618.      37510 58209 74944 59230 78164 06286 20899 86280 34825 34211
  619.      70679
  620.      ;Evaluation took 550 mSec (60 in gc) 36976 cells work, 1548 bytes other
  621.      #<unspecified>
  622.  
  623. PROBLEM
  624.      HOW TO FIX
  625.  
  626. Runs some and then machine crashes.
  627.      See above under machine crashes.
  628.  
  629. Runs some and then ERROR: ... (after a GC has happened)
  630.      Remove optimization option to C compiler and recompile.
  631.  
  632.      `#define SHORT_ALIGN' in `scmfig.h'.
  633.  
  634. Some symbol names print incorrectly.
  635.      Change memory model option to C compiler (or makefile).
  636.  
  637.      Check that `HEAP_SEG_SIZE' fits within `sizet'.
  638.  
  639.      Increase size of `HEAP_SEG_SIZE' (or `INIT_HEAP_SIZE' if it is
  640.      smaller than `HEAP_SEG_SIZE').
  641.  
  642. ERROR: Rogue pointer in Heap.
  643.      See above under machine crashes.
  644.  
  645. Newlines don't appear correctly in output files.
  646.      Check file mode (define OPEN_... in `Init.scm'
  647.  
  648. Spaces or control characters appear in symbol names
  649.      Check character defines in `scmfig.h'.
  650.  
  651. Negative numbers turn positive.
  652.      Check SRS in `scmfig.h'.
  653.  
  654. VMS: Couldn't unwind stack
  655. VAX: botched longjmp
  656.      `#define CHEAP_CONTIUATIONS' in `scmfig.h'.
  657.  
  658. Sparc(SUN-4) heap is growing out of control
  659.      You are experiencing a GC problem peculiar to the Sparc.  The
  660.      problem is that SCM doesn't know how to clear register windows.
  661.      Every location which is not reused still gets marked at GC time.
  662.      This causes lots of stuff which should be collected to not be.
  663.      This will be a problem with any *conservative* GC until we find
  664.      what instruction will clear the register windows.  This problem is
  665.      exacerbated by using lots of call-with-current-continuations.
  666.  
  667. 
  668. File: scm.info,  Node: Reporting Problems,  Prev: Testing,  Up: Installing SCM
  669.  
  670. Reporting Problems
  671. ==================
  672.  
  673. Reported problems and solutions are grouped under Compiling, Linking,
  674. Running, and Testing.  If you don't find your problem listed there, you
  675. can send a bug report to `jaffer@ai.mit.edu' or
  676. `bug-scm@scrg.cs.tcd.ie'.  The bug report should include:
  677.  
  678.   1. The version of SCM (printed when SCM is invoked with no arguments).
  679.  
  680.   2. The type of computer you are using.
  681.  
  682.   3. The name and version of your computer's operating system.
  683.  
  684.   4. The values of the environment variables `SCM_INIT_PATH' and
  685.      `SCHEME_LIBRARY_PATH'.
  686.  
  687.   5. The name and version of your C compiler.
  688.  
  689.   6. If you are using an executable from a distribution, the name,
  690.      vendor, and date of that distribution.  In this case,
  691.      corresponding with the vendor is recommended.
  692.  
  693. 
  694. File: scm.info,  Node: Standard Facilities,  Next: Packages,  Prev: Installing SCM,  Up: Top
  695.  
  696. Standard Facilities
  697. *******************
  698.  
  699. * Menu:
  700.  
  701. * Standards Compliance::        Links to sections in [R4RS] and [SLIB]
  702. * System Interface::            Like how to exit
  703. * Internal State::              GC, errors, and diagnostics
  704. * Miscellaneous Procedures::
  705. * Time::                        Both real time and processor time
  706. * Interrupts::                  and exceptions
  707. * Process Synchronization::     Because interrupts are preemptive
  708. * Files and Ports::
  709. * Soft Ports::                  Emulate I/O devices
  710. * Syntax Extensions::           and how to Define New Syntax
  711. * Low Level Syntactic Hooks::
  712.  
  713. 
  714. File: scm.info,  Node: Standards Compliance,  Next: System Interface,  Prev: Standard Facilities,  Up: Standard Facilities
  715.  
  716. Standards Compliance
  717. ====================
  718.  
  719. Scm conforms to the `IEEE Standard 1178-1990.  IEEE Standard for the
  720. Scheme Programming Language.' (*note Bibliography::.), and `Revised(4)
  721. Report on the Algorithmic Language Scheme'.  *Note Top: (r4rs)Top.  All
  722. the required features of these specifications are supported.  Many of
  723. the optional features are supported as well.
  724.  
  725. Optionals of [R4RS] Supported by SCM
  726. ------------------------------------
  727.  
  728. two clause `if': `(if <test> <consequent>)'
  729.      *Note Conditionals: (r4rs)Conditionals.
  730.  
  731. `let*'
  732. named `let'
  733.      *Note Binding constructs: (r4rs)Binding constructs.
  734.  
  735. `do'
  736.      *Note Iteration: (r4rs)Iteration.
  737.  
  738. All varieties of `define'
  739.      *Note Definitions: (r4rs)Definitions.
  740.  
  741. `list-tail'
  742.      *Note Pairs and lists: (r4rs)Pairs and lists.
  743.  
  744. `string-copy'
  745. `string-fill!'
  746.      *Note Strings: (r4rs)Strings.
  747.  
  748. `make-vector' of two arguments
  749. `vector-fill!'
  750.      *Note Vectors: (r4rs)Vectors.
  751.  
  752. `apply' of more than 2 arguments
  753.      *Note Control features: (r4rs)Control features.
  754.  
  755. `-' and `/' of more than 2 arguments
  756. `exp'
  757. `log'
  758. `sin'
  759. `cos'
  760. `tan'
  761. `asin'
  762. `acos'
  763. `atan'
  764. `sqrt'
  765. `expt'
  766. `make-rectangular'
  767. `make-polar'
  768. `real-part'
  769. `imag-part'
  770. `magnitude'
  771. `angle'
  772. `exact->inexact'
  773. `inexact->exact'
  774.      *Note Numerical operations: (r4rs)Numerical operations.
  775.  
  776. `delay'
  777. `force'
  778.      *Note Control features: (r4rs)Control features.
  779.  
  780. `with-input-from-file'
  781. `with-output-to-file'
  782.      *Note Ports: (r4rs)Ports.
  783.  
  784. `char-ready?'
  785.      *Note Input: (r4rs)Input.
  786.  
  787. `transcript-on'
  788. `transcript-off'
  789.      *Note System interface: (r4rs)System interface.
  790.  
  791. Optionals of [R4RS] not Supported by SCM
  792. ----------------------------------------
  793.  
  794. `numerator'
  795. `denominator'
  796. `rationalize'
  797.      *Note Numerical operations: (r4rs)Numerical operations.
  798.  
  799. [R4RS] appendix Macros
  800.      *Note Macros: (r4rs)Macros.
  801.  
  802. [SLIB] Features of SCM and SCMLIT
  803. ---------------------------------
  804.  
  805. `delay'
  806. `full-continuation'
  807. `ieee-p1178'
  808. `object-hash'
  809. `rev4-report'
  810. `source'
  811.      See SLIB file `Template.scm'.
  812.  
  813. `current-time'
  814.      *Note Time: (slib)Time.
  815.  
  816. `defmacro'
  817.      *Note Defmacro: (slib)Defmacro.
  818.  
  819. `dynamic-wind'
  820.      *Note Dynamic-Wind: (slib)Dynamic-Wind.
  821.  
  822. `eval'
  823.      *Note System: (slib)System.
  824.  
  825. `getenv'
  826. `system'
  827.      *Note System Interface: (slib)System Interface.
  828.  
  829. `hash'
  830.      *Note Hashing: (slib)Hashing.
  831.  
  832. `logical'
  833.      *Note Bit-Twiddling: (slib)Bit-Twiddling.
  834.  
  835. `multiarg-apply'
  836.      *Note Multi-argument Apply: (slib)Multi-argument Apply.
  837.  
  838. `multiarg/and-'
  839.      *Note Multi-argument / and -: (slib)Multi-argument / and -.
  840.  
  841. `rev4-optional-procedures'
  842.      *Note Rev4 Optional Procedures: (slib)Rev4 Optional Procedures.
  843.  
  844. `string-port'
  845.      *Note String Ports: (slib)String Ports.
  846.  
  847. `tmpnam'
  848.      *Note Input/Output: (slib)Input/Output.
  849.  
  850. `transcript'
  851.      *Note Transcripts: (slib)Transcripts.
  852.  
  853. `vicinity'
  854.      *Note Vicinity: (slib)Vicinity.
  855.  
  856. `with-file'
  857.      *Note With-File: (slib)With-File.
  858.  
  859. [SLIB] Features of SCM
  860. ----------------------
  861.  
  862. `array'
  863.      *Note Arrays: (slib)Arrays.
  864.  
  865. `array-for-each'
  866.      *Note Array Mapping: (slib)Array Mapping.
  867.  
  868. `bignum'
  869. `complex'
  870. `inexact'
  871. `rational'
  872. `real'
  873.      *Note Require: (slib)Require.
  874.  
  875. 
  876. File: scm.info,  Node: System Interface,  Next: Internal State,  Prev: Standards Compliance,  Up: Standard Facilities
  877.  
  878. System Interface
  879. ================
  880.  
  881. For documentation of the procedures `getenv' and `system' *Note System
  882. Interface: (slib)System Interface.
  883.  
  884.  - Function: quit
  885.  - Function: quit N
  886.  - Function: exit
  887.  - Function: exit N
  888.      Aliases for `exit' (*note exit: (slib)System.).  On many systems,
  889.      SCM can also tail-call another program.  *Note execp:
  890.      I/O-Extensions.
  891.  
  892.  - Function: vms-debug
  893.      If SCM is compiled under VMS these commands will invoke the editor
  894.      or debugger respectively.
  895.  
  896.  - Function: ed FILENAME
  897.      If SCM is compiled under VMS `ed' will invoke the editor with a
  898.      single the single argument FILENAME.
  899.  
  900.  - Function: ed ARG1 ...
  901.      Otherwise, the value of the environment variable `EDITOR' (or just
  902.      `ed' if it isn't defined) is invoked as a command with arguments
  903.      ARG1 ....
  904.  
  905.  - Function: program-arguments
  906.      Returns a list of strings of the arguments scm was called with.
  907.  
  908.  - Function: errno
  909.  - Function: errno N
  910.      With no argument returns the current value of the system variable
  911.      `errno'.  When given an argument, `errno' sets the system variable
  912.      `errno' to N and returns the previous value of `errno'.  `(errno
  913.      0)' will clear outstanding errors.  This is recommended after
  914.      `try-load' returns `#f' since this occurs when the file could not
  915.      be opened.
  916.  
  917.  - Function: perror STRING
  918.      Prints on standard error output the argument STRING, a colon,
  919.      followed by a space, the error message corresponding to the current
  920.      value of `errno' and a newline.  The value returned is unspecified.
  921.  
  922. 
  923. File: scm.info,  Node: Internal State,  Next: Miscellaneous Procedures,  Prev: System Interface,  Up: Standard Facilities
  924.  
  925. Internal State
  926. ==============
  927.  
  928.  - Variable: errobj
  929.      If SCM encounters a non-fatal error it aborts evaluation of the
  930.      current form, prints a message explaining the error, and resumes
  931.      the top level read-eval-print loop.  The value of ERROBJ is the
  932.      offending object if appropriate.  ERROBJ is *not* set from calls
  933.      to the procedure `error'.
  934.  
  935.  - Function: error ARG1 ARG2 ARG3 ...
  936.      Alias for *Note error: (slib)System.  Outputs an error message
  937.      containing the arguments, aborts evaluation of the current form and
  938.      resumes the top level read-eval-print loop.  Error is defined in
  939.      `Init.scm'; You change it to suit you.
  940.  
  941.  - Function: abort
  942.      Resumes the top level Read-Eval-Print loop.
  943.  
  944.  - Function: verbose N
  945.      Controls how much monitoring information is printed.  If N is:
  946.  
  947.     0
  948.           no prompt or information is printed.
  949.  
  950.     >= 1
  951.           a prompt is printed.
  952.  
  953.     >= 2
  954.           the CPU time is printed after each top level form evaluated.
  955.  
  956.     >= 3
  957.           messages about heap growth are printed.
  958.  
  959.     >= 4
  960.           garbage collection (*note Garbage Collection::.) messages are
  961.           printed.
  962.  
  963.     >= 5
  964.           a warning will be printed for each top-level symbol which is
  965.           defined more than one time.
  966.  
  967.  - Function: gc
  968.      Scans all of SCM objects and reclaims for further use those that
  969.      are no longer accessible.
  970.  
  971.  - Function: room
  972.  - Function: room #T
  973.      Prints out statistics about SCM's current use of storage.  `(room
  974.      #t)' also gives the hexadecimal heap segment and stack bounds.
  975.  
  976.  - Constant: *scm-version*
  977.      Contains the version string (e.g. `4e2') of SCM.
  978.  
  979. For other configuration constants and procedures *Note Configuration:
  980. (slib)Configuration.
  981.  
  982. 
  983. File: scm.info,  Node: Miscellaneous Procedures,  Next: Time,  Prev: Internal State,  Up: Standard Facilities
  984.  
  985. Miscellaneous Procedures
  986. ========================
  987.  
  988.  - Function: try-load FILENAME
  989.      If the string FILENAME names an existing file, the try-load
  990.      procedure reads Scheme source code expressions and definitions
  991.      from the file and evaluates them sequentially and returns `#t'.
  992.      If not, try-load returns `#f'.  The try-load procedure does not
  993.      affect the values returned by `current-input-port' and
  994.      `current-output-port'.
  995.  
  996.  - Variable: *load-pathname*
  997.      Is set to the pathname given as argument to `load', `try-load',
  998.      and `dyn:link' (*note Compiling And Linking::.).
  999.      `*load-pathname*' is used to compute the value of *Note
  1000.      program-vicinity: (slib)Vicinity.
  1001.  
  1002.  - Function: line-number
  1003.      Returns the current line number of the file currently being loaded.
  1004.  
  1005.  - Function: eval OBJ
  1006.      Alias for *Note eval: (slib)System.
  1007.  
  1008.  - Function: eval-string STR
  1009.      Returns the result of reading an expression from STR and
  1010.      evaluating it.  `eval-string' does not change `*load-pathname*' or
  1011.      `line-number'.
  1012.  
  1013.  - Function: load-string STR
  1014.      Reads and evaluates all the expressions from STR.  As with `load',
  1015.      the value returned is unspecified.  `eval-string' does not change
  1016.      `*load-pathname*' or `line-number'.
  1017.  
  1018.  - Function: vector-set-length! OBJECT LENGTH
  1019.      Change the length of string, vector, bit-vector, or uniform-array
  1020.      OBJECT to LENGTH.  If this shortens OBJECT then the remaining
  1021.      contents are lost.  If it enlarges OBJECT then the contents of the
  1022.      extended part are undefined but the original part is unchanged.
  1023.      It is an error to change the length of literal datums.  The new
  1024.      object is returned.
  1025.  
  1026.  - Function: copy-tree OBJ
  1027.      *Note copy-tree: (slib)Tree Operations.  This extends the SLIB
  1028.      version by also copying vectors.
  1029.  
  1030.  - Function: acons OBJ1 OBJ2 OBJ3
  1031.      Returns (cons (cons obj1 obj2) obj3).  The expression (set! a-list
  1032.      (acons key datum a-list)) adds a new association to a-list.
  1033.  
  1034.  - Function: terms
  1035.      This command displays the GNU General Public License.
  1036.  
  1037.  - Function: list-file FILENAME
  1038.      Displays the text contents of FILENAME.
  1039.  
  1040. 
  1041. File: scm.info,  Node: Time,  Next: Interrupts,  Prev: Miscellaneous Procedures,  Up: Standard Facilities
  1042.  
  1043. Time
  1044. ====
  1045.  
  1046.  - Constant: internal-time-units-per-second
  1047.      Is the integer number of internal time units in a second.
  1048.  
  1049.  - Function: get-internal-run-time
  1050.      Returns the integer run time in internal time units from an
  1051.      unspecified starting time.  The difference of two calls to
  1052.      `get-internal-run-time' divided by
  1053.      `internal-time-units-per-second' will give elapsed run time in
  1054.      seconds.
  1055.  
  1056.  - Function: get-internal-real-time
  1057.      Returns the integer time in internal time units from an unspecified
  1058.      starting time.  The difference of two calls to
  1059.      `get-internal-real-time' divided by
  1060.      `interal-time-units-per-second' will give elapsed real time in
  1061.      seconds.
  1062.  
  1063.  - Function: current-time
  1064.      Returns the time since 00:00:00 GMT, January 1, 1970, measured in
  1065.      seconds.  *Note current-time: (slib)Time.  `current-time' is used
  1066.      in *Note Time: (slib)Time.
  1067.  
  1068. 
  1069. File: scm.info,  Node: Interrupts,  Next: Process Synchronization,  Prev: Time,  Up: Standard Facilities
  1070.  
  1071. Interrupts
  1072. ==========
  1073.  
  1074.  - Function: ticks N
  1075.      Returns the number of ticks remaining till the next tick interrupt.
  1076.      Ticks are an arbitrary unit of evaluation.  Ticks can vary greatly
  1077.      in the amount of time they represent.
  1078.  
  1079.      If N is 0, any ticks request is canceled.  Otherwise a
  1080.      `ticks-interrupt' will be signaled N from the current time.
  1081.      `ticks' is supported if SCM is compiled with the `ticks' flag
  1082.      defined.
  1083.  
  1084.  - Callback procedure: ticks-interrupt ...
  1085.      Establishes a response for tick interrupts.  Another tick
  1086.      interrupt will not occur unless `ticks' is called again.  Program
  1087.      execution will resume if the handler returns.  This procedure
  1088.      should (abort) or some other action which does not return if it
  1089.      does not want processing to continue.
  1090.  
  1091.  - Function: alarm SECS
  1092.      Returns the number of seconds remaining till the next alarm
  1093.      interrupt.  If SECS is 0, any alarm request is canceled.
  1094.      Otherwise an `alarm-interrupt' will be signaled SECS from the
  1095.      current time.  ALARM is not supported on all systems.
  1096.  
  1097.  - Callback procedure: user-interrupt ...
  1098.  - Callback procedure: alarm-interrupt ...
  1099.      Establishes a response for `SIGINT' (control-C interrupt) and
  1100.      `SIGALRM' interrupts.  Program execution will resume if the handler
  1101.      returns.  This procedure should `(abort)' or some other action
  1102.      which does not return if it does not want processing to continue
  1103.      after it returns.
  1104.  
  1105.      Interrupt handlers are disabled during execution `system' and `ed'
  1106.      procedures.
  1107.  
  1108.      To unestablish a response for an interrupt set the handler symbol
  1109.      to `#f'.  For instance, `(set! user-interrupt #f)'.
  1110.  
  1111.  - Callback procedure: out-of-storage ...
  1112.  - Callback procedure: could-not-open ...
  1113.  - Callback procedure: end-of-program ...
  1114.  - Callback procedure: hang-up ...
  1115.  - Callback procedure: arithmetic-error ...
  1116.      Establishes a response for storage allocation error, file opening
  1117.      error, end of program, SIGHUP (hang up interrupt) and arithmetic
  1118.      errors respectively.  This procedure should (abort) or some other
  1119.      action which does not return if it does not want the default error
  1120.      message to also be displayed.  If no procedure is defined for
  1121.      HANG-UP then END-OF-PROGRAM (if defined) will be called.
  1122.  
  1123.      To unestablish a response for an error set the handler symbol to
  1124.      `#f'.  For instance, `(set! could-not-open #f)'.
  1125.  
  1126. 
  1127. File: scm.info,  Node: Process Synchronization,  Next: Files and Ports,  Prev: Interrupts,  Up: Standard Facilities
  1128.  
  1129. Process Synchronization
  1130. =======================
  1131.  
  1132.  - Function: make-arbiter NAME
  1133.      Returns an object of type arbiter and name NAME.  Its state is
  1134.      initially unlocked.
  1135.  
  1136.  - Function: try-arbiter ARBITER
  1137.      Returns `#t' and locks ARBITER if ARBITER was unlocked.
  1138.      Otherwise, returns `#f'.
  1139.  
  1140.  - Function: release-arbiter ARBITER
  1141.      Returns `#t' and unlocks ARBITER if ARBITER was locked.
  1142.      Otherwise, returns `#f'.
  1143.  
  1144. 
  1145. File: scm.info,  Node: Files and Ports,  Next: Soft Ports,  Prev: Process Synchronization,  Up: Standard Facilities
  1146.  
  1147. Files and Ports
  1148. ===============
  1149.  
  1150. These procedures generalize and extend the standard capabilities in
  1151. *Note Ports: (r4rs)Ports.
  1152.  
  1153.  - Function: open-file STRING MODES
  1154.      Returns a port capable of receiving or delivering characters as
  1155.      specified by the MODES string.  If a file cannot be opened `#f' is
  1156.      returned.
  1157.  
  1158.  - Constant: open_read
  1159.  - Constant: open_write
  1160.  - Constant: open_both
  1161.      Contain modes strings specifying that a file is to be opened for
  1162.      reading, writing, and both reading and writing respectively.
  1163.  
  1164.  - Function: _ionbf MODESTR
  1165.      Returns a version of modestr which when open-file is called with
  1166.      it as the second argument will return an unbuffered port.  A
  1167.      non-file input-port must be unbuffered in order for char-ready? to
  1168.      work correctly on it.  The initial value of (current-input-port)
  1169.      is unbuffered if the platform supports it.
  1170.  
  1171.  - Function: close-port PORT
  1172.      Closes PORT.  The same as close-input-port and close-output-port.
  1173.  
  1174.  - Function: open-io-file FILENAME
  1175.  - Function: close-io-port PORT
  1176.      These functions are analogous to the standard scheme file
  1177.      functions.  The ports are open to FILENAME in read/write mode.
  1178.      Both input and output functions can be used with io-ports.  An end
  1179.      of file must be read or a file-set-position done on the port
  1180.      between a read operation and a write operation or vice-versa.
  1181.  
  1182.  - Function: current-error-port
  1183.      Returns the current port to which diagnostic output is directed.
  1184.  
  1185.  - Function: with-error-to-file STRING THUNK
  1186.      THUNK must be a procedure of no arguments, and string must be a
  1187.      string naming a file.  The file is opened for output, an output
  1188.      port connected to it is made the default value returned by
  1189.      current-error-port, and the THUNK is called with no arguments.
  1190.      When the thunk returns, the port is closed and the previous
  1191.      default is restored.  With-error-to-file returns the value yielded
  1192.      by THUNK.
  1193.  
  1194.  - Function: with-input-from-port PORT THUNK
  1195.  - Function: with-output-to-port PORT THUNK
  1196.  - Function: with-error-to-port PORT THUNK
  1197.      These routines differ from with-input-from-file,
  1198.      with-output-to-file, and with-error-to-file in that the first
  1199.      argument is a port, rather than a string naming a file.
  1200.  
  1201. 
  1202. File: scm.info,  Node: Soft Ports,  Next: Syntax Extensions,  Prev: Files and Ports,  Up: Standard Facilities
  1203.  
  1204. Soft Ports
  1205. ==========
  1206.  
  1207. A "soft-port" is a port based on a vector of procedures capable of
  1208. accepting or delivering characters.  It allows emulation of I/O ports.
  1209.  
  1210.  - Function: make-soft-port VECTOR MODES
  1211.      Returns a port capable of receiving or delivering characters as
  1212.      specified by the MODES string (*note open-file: Files and Ports.).
  1213.      VECTOR must be a vector of length 6.  Its components are as
  1214.      follows:
  1215.  
  1216.        0. procedure accepting one character for output
  1217.  
  1218.        1. procedure accepting a string for output
  1219.  
  1220.        2. thunk for flushing output
  1221.  
  1222.        3. thunk for getting one character
  1223.  
  1224.        4. thunk for closing port (not by garbage collection)
  1225.  
  1226.      For an output-only port only elements 0, 1, 2, and 4 need be
  1227.      procedures.  For an input-only port only elements 3 and 4 need be
  1228.      procedures.  Thunks 2 and 4 can instead be `#f' if there is no
  1229.      useful operation for them to perform.
  1230.  
  1231.      If thunk 3 returns `#f' or an `eof-object' (*note eof-object?:
  1232.      (r4rs)Input.) it indicates that the port has reached end-of-file.
  1233.      For example:
  1234.  
  1235.           (define stdout (current-output-port))
  1236.           (define p (make-soft-port
  1237.                      (vector
  1238.                       (lambda (c) (write c stdout))
  1239.                       (lambda (s) (display s stdout))
  1240.                       (lambda () (display "." stdout))
  1241.                       (lambda () (char-upcase (read-char)))
  1242.                       (lambda () (display "@" stdout)))
  1243.                      "rw"))
  1244.           
  1245.           (write p p) => #<input-output-soft#\space45d10#\>
  1246.  
  1247. 
  1248. File: scm.info,  Node: Syntax Extensions,  Next: Low Level Syntactic Hooks,  Prev: Soft Ports,  Up: Standard Facilities
  1249.  
  1250. Syntax Extensions
  1251. =================
  1252.  
  1253.  - Read syntax: #. EXPRESSION
  1254.      Is read as the object resulting from the evaluation of EXPRESSION.
  1255.      This substitution occurs even inside quoted structure.
  1256.  
  1257.      In order to allow compiled code to work with `#.' it is good
  1258.      practice to define those symbols used inside of EXPRESSION with
  1259.      `#.(define ...)'.  For example:
  1260.  
  1261.           #.(define foo 9)                        => #<unspecified>
  1262.           '(#.foo #.(+ foo foo))                  => (9 18)
  1263.  
  1264.  - Read syntax: #+ FEATURE FORM
  1265.      If feature is `provided?' (by `*features*') then FORM is read as a
  1266.      scheme expression.  If not, then FORM is treated as whitespace.
  1267.  
  1268.      Feature is a boolean expression composed of symbols and `and',
  1269.      `or', and `not' of boolean expressions.
  1270.  
  1271.      For more information on `provided?' and `*features*', *Note
  1272.      Require: (slib)Require.
  1273.  
  1274.  - Read syntax: #- FEATURE FORM
  1275.      is equivalent to `#+(not feature) expression'.
  1276.  
  1277.  - Read syntax: #' FORM
  1278.      is equivalent to FORM (for compatibility with common-lisp).
  1279.  
  1280.  - Read syntax: #| ANY THING |#
  1281.      Is a balanced comment.  Everything up to the matching `|#' is
  1282.      ignored by the `read'.  Nested `#|...|#' can occur inside ANY
  1283.      THING.
  1284.  
  1285.  - Read syntax: #! ANY THING
  1286.      On the first line of a file will be ignored when loaded by SCM.
  1287.      This makes SCM files usable as POSIX shell scripts if the first
  1288.      line is:
  1289.  
  1290.           #!/usr/local/bin/scm
  1291.  
  1292.      When such a file is invoked it executes /usr/local/bin/scm with the
  1293.      name of this file as the first argument.  The following shell
  1294.      script will print factorial of its argument:
  1295.           #!/usr/local/bin/scm
  1296.           ;;; -*-scheme-*- tells emacs this is a scheme file.
  1297.           (define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n)))))
  1298.           (display (fact (string->number (caddr (program-arguments)))))
  1299.           (newline)
  1300.           (quit)
  1301.  
  1302.      This technique has some drawbacks:
  1303.         * Some Unixes limit the length of the `#!' interpreter line to
  1304.           the size of an object file header, which can be as small as
  1305.           32 bytes.
  1306.  
  1307.         * A full, explicit pathname must be specified, perhaps
  1308.           requiring more than 32 bytes and making scripts vulnerable to
  1309.           programs being moved.
  1310.  
  1311.      The following approach solves both problems - at the expense of
  1312.      slightly slower startup.  `type;' should appear on every line to be
  1313.      executed by the shell.  These lines do not have the length
  1314.      restriction mentioned above.  Also, `/bin/sh' searches the
  1315.      directories listed in the `PATH' environment variable for `scm',
  1316.      eliminating the need to know absolute locations in order to invoke
  1317.      a program.
  1318.           #!/bin/sh
  1319.           type;exec scm $0 $*
  1320.           ;;; -*-scheme-*- tells emacs this is a scheme file.
  1321.           (define (fact n) (if (< n 2) 1 (* n (fact (+ -1 n)))))
  1322.           (display (fact (string->number (caddr (program-arguments)))))
  1323.           (newline)
  1324.           (quit)
  1325.  
  1326.  - Special Form: defined? SYMBOL
  1327.      Equivalent to `#t' if SYMBOL is a syntactic keyword (such as `if')
  1328.      or a symbol with a value in the top level environment (*note
  1329.      Variables and regions: (r4rs)Variables and regions.).  Otherwise
  1330.      equivalent to `#f'.
  1331.  
  1332.  - Special Form: defvar IDENTIFIER INITIAL-VALUE
  1333.      If IDENTIFIER is unbound in the top level environment, then
  1334.      IDENTIFIER is `define'd to the result of evaluating the form
  1335.      INITIAL-VALUE as if the `defvar' form were instead the form
  1336.      `(define identifier initial-value)' .  If IDENTIFIER already has a
  1337.      value, then INITIAL-VALUE is *not* evaluated and IDENTIFIER's
  1338.      value is not changed.
  1339.  
  1340. SCM also supports the following constructs from Common Lisp:
  1341. `defmacro', `macroexpand', `macroexpand-1', and `gentemp'.  *Note
  1342. Defmacro: (slib)Defmacro.
  1343.  
  1344. 
  1345. File: scm.info,  Node: Low Level Syntactic Hooks,  Prev: Syntax Extensions,  Up: Standard Facilities
  1346.  
  1347. Low Level Syntactic Hooks
  1348. =========================
  1349.  
  1350.  - Callback procedure: read:sharp C PORT
  1351.      If a # followed by a character (for a non-standard syntax) is
  1352.      encountered by `read', `read' will call the value of the symbol
  1353.      `read:sharp' with arguments the character and the port being read
  1354.      from.  The value returned by this function will be the value of
  1355.      `read' for this expression unless the function returns
  1356.      `#<unspecified>' in which case the expression will be treated as
  1357.      whitespace.  `#<unspecified>' is the value returned by the
  1358.      expression `(if #f #f)'.
  1359.  
  1360.      *Note:* When adding new # syntaxes, have your code save the
  1361.      previous value of `read:sharp' when defining it.  Call this saved
  1362.      value if an invocation's syntax is not recognized.  This will allow
  1363.      `#+', `#-', `#!', and *Note Uniform Array::s to still be supported
  1364.      (as they use `read:sharp').
  1365.  
  1366.  - Function: procedure->syntax PROC
  1367.      Returns a "macro" which, when a symbol defined to this value
  1368.      appears as the first symbol in an expression, returns the result
  1369.      of applying PROC to the expression and the environment.
  1370.  
  1371.  - Function: procedure->macro PROC
  1372.  - Function: procedure->memoizing-macro PROC
  1373.      Returns a "macro" which, when a symbol defined to this value
  1374.      appears as the first symbol in an expression, evaluates the result
  1375.      of applying PROC to the expression and the environment.  The value
  1376.      returned from PROC which has been passed to
  1377.      `PROCEDURE->MEMOIZING-MACRO' replaces the form passed to PROC.
  1378.      For example:
  1379.  
  1380.           (define trace
  1381.             (procedure->macro
  1382.              (lambda (x env) `(set! ,(cadr x) (tracef ,(cadr x) ',(cadr x))))))
  1383.           
  1384.           (trace foo) == (set! foo (tracef foo 'foo)).
  1385.  
  1386.      An "environment" is a list of "environment frames".  There are 2
  1387.      types of environment frames:
  1388.  
  1389.     `((lambda (variable1 ...) ...) value1 ...)'
  1390.     `(let ((variable1 value1) (variable2 value2) ...) ...)'
  1391.     `(letrec ((variable1 value1)  ...) ...)'
  1392.           result in a single enviroment frame:
  1393.                ((variable1 ...) value1 ...)
  1394.  
  1395.     `(let ((variable1 value1)) ...)'
  1396.     `(let* ((variable1 value1) ...) ...)'
  1397.           result in an environment frame for each variable:
  1398.                (variable1 . value1) (variable2 .  value2) ...
  1399.  
  1400.  - Special Form: @apply PROCEDURE ARGUMENT-LIST
  1401.      Returns the result of applying procedure to argument-list.  (apply
  1402.      procedure argument-list) will produce the same result.
  1403.  
  1404.  - Special Form: @call-with-current-continuation PROCEDURE)
  1405.      Returns the result of applying procedure to the current
  1406.      continuation.  `(call-with-current-continuation PROCEDURE)' will
  1407.      have the same effect.
  1408.  
  1409. 
  1410. File: scm.info,  Node: Packages,  Next: Guile Facilities,  Prev: Standard Facilities,  Up: Top
  1411.  
  1412. Packages
  1413. ********
  1414.  
  1415. * Menu:
  1416.  
  1417. * Compiling And Linking::       and Dynamic Linking
  1418. * Numeric::
  1419. * Arrays::                      As in APL
  1420. * I/O-Extensions::              'i/o-extensions
  1421. * Posix Extensions::
  1422. * Regular Expression Pattern Matching::  'regex
  1423. * Line Editing::
  1424. * Curses::                      Screen Control
  1425. * Sockets::                     Cruise the Net
  1426.  
  1427.